Chicken » Unit posix

TOC »

Unit posix

Unit posix

This unit provides services as used on many UNIX-like systems. Note that the following definitions are not all available on non-UNIX systems like Windows. See below for Windows specific notes.

This unit uses the regex, scheduler, extras and utils units.

All errors related to failing file-operations will signal a condition of kind (exn i/o file).

Constants

File-control Commands

fcntl/dupfd constant
fcntl/getfd constant
fcntl/setfd constant
fcntl/getfl constant
fcntl/setfl constant: Operations used with file-control.

Standard I/O file-descriptors

fileno/stdin constant
fileno/stdout constant
fileno/stderr constant: Standard I/O file descriptor numbers, used with procedures such as open-input-file* which take file descriptors.

Open flags

open/rdonly constant
open/wronly constant
open/rdwr constant
open/read constant
open/write constant
open/creat constant
open/append constant
open/excl constant
open/noctty constant
open/nonblock constant
open/trunc constant
open/sync constant
open/fsync constant
open/binary constant
open/text constant: Open flags used with the file-open procedure. open/read is a convenience synonym for open/rdonly, as is open/write for open/wronly.

Permission bits

perm/irusr constant
perm/iwusr constant
perm/ixusr constant
perm/irgrp constant
perm/iwgrp constant
perm/ixgrp constant
perm/iroth constant
perm/iwoth constant
perm/ixoth constant
perm/irwxu constant
perm/irwxg constant
perm/irwxo constant
perm/isvtx constant
perm/isuid constant
perm/isgid constant: Permission bits used with, for example, file-open.

Directories

change-directory

(change-directory NAME) procedure: Changes the current working directory to NAME.

current-directory

(current-directory [DIR]) procedure: Returns the name of the current working directory. If the optional argument DIR is given, then (current-directory DIR) is equivalent to (change-directory DIR).

create-directory

(create-directory NAME #!optional PARENTS?) procedure: Creates a directory with the pathname NAME. If the PARENTS? argument is given and not false, any nonexistent parent directories are also created.

delete-directory

(delete-directory NAME [RECURSIVE]) procedure: Deletes the directory with the pathname NAME. If RECURSIVE is not given or false, then the directory has to be empty.

directory?

(directory? FILE) procedure: Returns #t if FILE designates directory. Otherwise, it returns #f. FILE may be a pathname or a file-descriptor.

glob

(glob PATTERN1 ...) procedure: Returns a list of the pathnames of all existing files matching PATTERN1 ..., which should be strings containing the usual file-patterns (with * matching zero or more characters and ? matching zero or one character).

set-root-directory!

(set-root-directory! STRING) procedure: Sets the root directory for the current process to the path given in STRING (using the chroot function). If the current process has no root permissions, the operation will fail.

Pipes

call-with-output-pipe

(call-with-input-pipe CMDLINE PROC [MODE]) procedure
(call-with-output-pipe CMDLINE PROC [MODE]) procedure: Call PROC with a single argument: a input- or output port for a pipe connected to the subprocess named in CMDLINE. If PROC returns normally, the pipe is closed and any result values are returned.

close-output-pipe

(close-input-pipe PORT) procedure
(close-output-pipe PORT) procedure: Closes the pipe given in PORT and waits until the connected subprocess finishes. The exit-status code of the invoked process is returned.

create-pipe

(create-pipe) procedure: The fundamental pipe-creation operator. Calls the C function pipe() and returns 2 values: the file-descriptors of the input- and output-ends of the pipe.

open-input-pipe

(open-input-pipe CMDLINE [MODE]) procedure: Spawns a subprocess with the command-line string CMDLINE and returns a port, from which the output of the process can be read. If MODE is specified, it should be the keyword #:text (the default) or #:binary.

open-output-pipe

(open-output-pipe CMDLINE [MODE]) procedure: Spawns a subprocess with the command-line string CMDLINE and returns a port. Anything written to that port is treated as the input for the process. If MODE is specified, it should be the keyword #:text (the default) or #:binary.

pipe/buf

This variable contains the maximal number of bytes that can be written atomically into a pipe or FIFO.

with-output-to-pipe

(with-input-from-pipe CMDLINE THUNK [MODE]) procedure

(with-output-to-pipe CMDLINE THUNK [MODE]) procedure

Temporarily set the value of current-input-port/current-output-port to a port for a pipe connected to the subprocess named in CMDLINE and call the procedure THUNK with no arguments. After THUNK returns normally the pipe is closed and the standard input-/output port is restored to its previous value and any result values are returned.

(with-output-to-pipe
  "gs -dNOPAUSE -sDEVICE=jpeg -dBATCH -sOutputFile=signballs.jpg -g600x600 -q -"
  (lambda ()
    (print #<<EOF
 %!IOPSC-1993 %%Creator: HAYAKAWA Takashi<xxxxxxxx@xx.xxxxxx.xx.xx>
 /C/neg/d/mul/R/rlineto/E/exp/H{{cvx def}repeat}def/T/dup/g/gt/r/roll/J/ifelse 8
 H/A/copy(z&v4QX&93r9AxYQOZomQalxS2w!!O&vMYa43d6r93rMYvx2dca!D&cjSnjSnjjS3o!v&6A
 X&55SAxM1CD7AjYxTTd62rmxCnTdSST0g&12wECST!&!J0g&D1!&xM0!J0g!l&544dC2Ac96ra!m&3A
 F&&vGoGSnCT0g&wDmlvGoS8wpn6wpS2wTCpS1Sd7ov7Uk7o4Qkdw!&Mvlx1S7oZES3w!J!J!Q&7185d
 Z&lx1CS9d9nE4!k&X&MY7!&1!J!x&jdnjdS3odS!N&mmx1C2wEc!G&150Nx4!n&2o!j&43r!U&0777d
 ]&2AY2A776ddT4oS3oSnMVC00VV0RRR45E42063rNz&v7UX&UOzF!F!J![&44ETCnVn!a&1CDN!Y&0M
 V1c&j2AYdjmMdjjd!o&1r!M){( )T 0 4 3 r put T(/)g{T(9)g{cvn}{cvi}J}{($)g[]J}J
 cvx}forall/moveto/p/floor/w/div/S/add 29 H[{[{]setgray fill}for Y}for showpage
 EOF
 ) ) )

Fifos

create-fifo

(create-fifo FILENAME [MODE]) procedure

Creates a FIFO with the name FILENAME and the permission bits MODE, which defaults to

 (+ perm/irwxu perm/irwxg perm/irwxo)

fifo?

(fifo? FILE) procedure: Returns #t if FILE names a FIFO. FILE may be a filename or a file-descriptor.

File descriptors and low-level I/O

duplicate-fileno

(duplicate-fileno OLD [NEW]) procedure: If NEW is given, then the file-descriptor NEW is opened to access the file with the file-descriptor OLD. Otherwise a fresh file-descriptor accessing the same file as OLD is returned.

file-close

(file-close FILENO) procedure: Closes the input/output file with the file-descriptor FILENO.

file-open

(file-open FILENAME FLAGS [MODE]) procedure

Opens the file specified with the string FILENAME and open-flags FLAGS using the C function open(2). On success a file-descriptor for the opened file is returned.

FLAGS is a bitmask of open/... values ored together using bitwise-ior (or simply added together). You must provide exactly one of the access flags open/rdonly, open/wronly, or open/rdwr. Additionally, you may provide zero or more creation flags (open/creat, open/excl, open/trunc, and open/noctty) and status flags (the remaining open/... values). For example, to open a possibly new output file for appending:

(file-open "/tmp/hen.txt" (+ open/wronly open/append open/creat))

The optional MODE should be a bitmask composed of one or more permission values like perm/irusr and is only relevant when a new file is created. The default mode is perm/irwxu | perm/irgrp | perm/iroth.

file-mkstemp

(file-mkstemp TEMPLATE-FILENAME) procedure

Create a file based on the given TEMPLATE-FILENAME, in which the six last characters must be XXXXXX. These will be replaced with a string that makes the filename unique. The file descriptor of the created file and the generated filename is returned. See the mkstemp(3) manual page for details on how this function works. The template string given is not modified.

Example usage:

 (let-values (((fd temp-path) (file-mkstemp "/tmp/mytemporary.XXXXXX")))
  (let ((temp-port (open-output-file* fd)))
    (format temp-port "This file is ~A.~%" temp-path)
    (close-output-port temp-port)))

file-read

(file-read FILENO SIZE [BUFFER]) procedure: Reads SIZE bytes from the file with the file-descriptor FILENO. If a string or bytevector is passed in the optional argument BUFFER, then this string will be destructively modified to contain the read data. This procedure returns a list with two values: the buffer containing the data and the number of bytes read.

file-select

(file-select READFDLIST WRITEFDLIST [TIMEOUT]) procedure: Waits until any of the file-descriptors given in the lists READFDLIST and WRITEFDLIST is ready for input or output, respectively. If the optional argument TIMEOUT is given and not false, then it should specify the number of seconds after which the wait is to be aborted (the value may be a floating point number). This procedure returns two values: the lists of file-descriptors ready for input and output, respectively. READFDLIST and WRITEFDLIST may also by file-descriptors instead of lists. In this case the returned values are booleans indicating whether input/output is ready by #t or #f otherwise. You can also pass #f as READFDLIST or WRITEFDLIST argument, which is equivalent to ().

file-write

(file-write FILENO BUFFER [SIZE]) procedure: Writes the contents of the string or bytevector BUFFER into the file with the file-descriptor FILENO. If the optional argument SIZE is given, then only the specified number of bytes are written.

file-control

(file-control FILENO COMMAND [ARGUMENT]) procedure: Performs the fcntl operation COMMAND with the given FILENO and optional ARGUMENT. The return value is meaningful depending on the COMMAND.

open-input-file*

open-output-file*

(open-input-file* FILENO [OPENMODE]) procedure
(open-output-file* FILENO [OPENMODE]) procedure: Opens file for the file-descriptor FILENO for input or output and returns a port. FILENO should be a positive exact integer. OPENMODE specifies an additional mode for opening the file (currently only the keyword #:append is supported, which opens an output-file for appending).

port->fileno

(port->fileno PORT) procedure: If PORT is a file- or tcp-port, then a file-descriptor is returned for this port. Otherwise an error is signaled.

Retrieving file attributes

file-access-time

file-change-time

file-modification-time

(file-access-time FILE) procedure

(file-change-time FILE) procedure

(file-modification-time FILE) procedure

(set! (file-modification-time FILE) SECONDS) procedure

Returns time (in seconds) of the last access, modification or change of FILE. FILE may be a filename or a file-descriptor. If the file does not exist, an error is signaled.

(set! (file-modification-time FILE) SECONDS) sets the access- and modification time of FILE to SECONDS.

file-stat

(file-stat FILE [LINK]) procedure

Returns a 13-element vector with the following contents: inode-number, mode (as with file-permissions), number of hard links, uid of owner (as with file-owner), gid of owner, size (as with file-size) and access-, change- and modification-time (as with file-access-time, file-change-time and file-modification-time, device id, device type (for special file inode, blocksize and blocks allocated. On Windows systems the last 4 values are undefined.

By default, symbolic links are followed and the status of the referenced file is returned; however, if the optional argument LINK is given and not #f, the status of the link itself is returned.

Note that for very large files, the file-size value may be an inexact integer.

file-position

(file-position FILE) procedure: Returns the current file position of FILE, which should be a port or a file-descriptor.

file-size

(file-size FILE) procedure: Returns the size of the file designated by FILE. FILE may be a filename or a file-descriptor. If the file does not exist, an error is signaled. Note that for very large files, file-size may return an inexact integer.

regular-file?

(regular-file? FILENAME) procedure: Returns true, if FILENAME names a regular file (not a directory, socket, etc.) This operation follows symbolic links; use either symbolic-link? or file-type if you need to test for symlinks.

file-owner

(file-owner FILE) procedure: Returns the user-id of FILE. FILE may be a filename or a file-descriptor.

file-permissions

(file-permissions FILE) procedure: Returns the permission bits for FILE. You can test this value by performing bitwise operations on the result and the perm/... values. FILE may be a filename or a file-descriptor.

file-read-access?

file-write-access?

file-execute-access?

(file-read-access? FILENAME) procedure
(file-write-access? FILENAME) procedure
(file-execute-access? FILENAME) procedure: These procedures return #t if the current user has read, write or execute permissions on the file named FILENAME.

file-type

(file-type FILE [LINK [ERROR]]) procedure

Returns the file-type for FILE, which should be a filename or file-descriptor. If LINK is given and true, symbolic-links are not followed:

 regular-file
 directory
 fifo
 socket
 symbolic-link
 character-device
 block-device

Note that not all types are supported on every platform. If ERROR is given and false, file-type signals an error if the file does not exist.

character-device?

block-device?

socket?

(character-device? FILE) procedure
(block-device? FILE) procedure
(socket? FILE) procedure: These procedures return #t if FILE given is of the appropriate type. FILE may be a filename or a file-descriptor. Note that these operations follow symbolic links. If the file does not exist, #f is returned.

Changing file attributes

file-truncate

(file-truncate FILE OFFSET) procedure: Truncates the file FILE to the length OFFSET, which should be an integer. If the file-size is smaller or equal to OFFSET then nothing is done. FILE should be a filename or a file-descriptor.

set-file-position!

(set-file-position! FILE POSITION [WHENCE]) procedure

(set! (file-position FILE) POSITION) procedure

Sets the current read/write position of FILE to POSITION, which should be an exact integer. FILE should be a port or a file-descriptor. WHENCE specifies how the position is to interpreted and should be one of the values seek/set, seek/cur and seek/end. It defaults to seek/set.

Exceptions: (exn bounds), (exn i/o file)

change-file-mode

(change-file-mode FILENAME MODE) procedure: Changes the current file mode of the file named FILENAME to MODE using the chmod() system call. The perm/... variables contain the various permission bits and can be combinded with the bitwise-ior procedure.

change-file-owner

(change-file-owner FILENAME UID GID) procedure: Changes the owner information of the file named FILENAME to the user- and group-ids UID and GID (which should be exact integers) using the chown() system call.

file-creation-mode

(file-creation-mode MODE) procedure

Returns the initial file permissions used for newly created files (as with umask(2). You can set the mode by executing

 (set! (file-creation-mode) MODE)

 (file-creation-mode MODE)

where MODE is a bitwise combination of one or more of the perm/... flags.

Processes

current-process-id

(current-process-id) procedure: Returns the process ID of the current process.

parent-process-id

(parent-process-id) procedure: Returns the process ID of the parent of the current process.

process-group-id

(process-group-id PID) procedure: Returns the process group ID of the process specified by PID.

process-execute

(process-execute PATHNAME [ARGUMENT-LIST [ENVIRONMENT-LIST]]) procedure: Creates a new child process and replaces the running process with it using the C library function execvp(3). If the optional argument ARGUMENT-LIST is given, then it should contain a list of strings which are passed as arguments to the subprocess. If the optional argument ENVIRONMENT-LIST is supplied, then the library function execve(2) is used, and the environment passed in ENVIRONMENT-LIST (which should be of the form ("<NAME>=<VALUE>" ...) is given to the invoked process. Note that execvp(3) respects the current setting of the PATH environment variable while execve(3) does not.

process-fork

(process-fork [THUNK]) procedure: Creates a new child process with the UNIX system call fork(). Returns either the PID of the child process or 0. If THUNK is given, then the child process calls it as a procedure with no arguments and terminates.

process-run

(process-run COMMANDLINE) procedure

(process-run COMMAND ARGUMENT-LIST) procedure

Creates a new child process. The PID of the new process is returned.

The single parameter version passes the COMMANDLINE to the system shell, so usual argument expansion can take place.
The multiple parameter version directly invokes the COMMAND with the ARGUMENT-LIST.

process-signal

(process-signal PID [SIGNAL]) procedure: Sends SIGNAL to the process with the id PID using the UNIX system call kill(). SIGNAL defaults to the value of the variable signal/term.

process-wait

(process-wait [PID [NOHANG]]) procedure

Suspends the current process until the child process with the id PID has terminated using the UNIX system call waitpid(). If PID is not given, then this procedure waits for any child process. If NOHANG is given and not #f then the current process is not suspended. This procedure returns three values:

PID or 0, if NOHANG is true and the child process has not terminated yet.
#t if the process exited normally or #f otherwise.
either the exit status, if the process terminated normally or the signal number that terminated/stopped the process.

Note that suspending the current process implies that all threads are suspended as well.

process

(process COMMANDLINE) procedure

(process COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST]) procedure

Creates a subprocess and returns three values: an input port from which data written by the sub-process can be read, an output port from which any data written to will be received as input in the sub-process and the process-id of the started sub-process. Blocking reads and writes to or from the ports returned by process only block the current thread, not other threads executing concurrently.

The single parameter version passes the string COMMANDLINE to the host-system's shell that is invoked as a subprocess.
The multiple parameter version directly invokes the COMMAND as a subprocess. The ARGUMENT-LIST is directly passed, as is ENVIRONMENT-LIST.

Not using the shell may be preferrable for security reasons.

Once both the input- and output ports are closed, an implicit waitpid(3) is done to wait for the subprocess to finish or to reap a subprocess that has terminated. If the subprocess has not finished, waiting for it will necessarily block all executing threads.

process*

(process* COMMANDLINE) procedure
(process* COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST]) procedure: Like process but returns 4 values: an input port from which data written by the sub-process can be read, an output port from which any data written to will be received as input in the sub-process, the process-id of the started sub-process, and an input port from which data written by the sub-process to stderr can be read.

sleep

(sleep SECONDS) procedure: Puts the process to sleep for SECONDS. Returns either 0 if the time has completely elapsed, or the number of remaining seconds, if a signal occurred.

create-session

(create-session) procedure: Creates a new session if the calling process is not a process group leader and returns the session ID.

Hard and symbolic links

symbolic-link?

(symbolic-link? FILENAME) procedure: Returns true, if FILENAME names a symbolic link. If no such file exists, #f is returned. This operation does not follow symbolic links itself.

create-symbolic-link

(create-symbolic-link OLDNAME NEWNAME) procedure: Creates a symbolic link with the filename NEWNAME that points to the file named OLDNAME.

read-symbolic-link

(read-symbolic-link FILENAME [CANONICALIZE]) procedure: Returns the filename to which the symbolic link FILENAME points. If CANONICALIZE is given and true, then symbolic links are resolved repeatedly until the result is not a link.

file-link

(file-link OLDNAME NEWNAME) procedure: Creates a hard link from OLDNAME to NEWNAME (both strings).

Retrieving user & group information

current-user-id

(current-user-id) procedure

[setter] (set! (current-user-id) UID)

Get or set the real user-id of the current process.

current-effective-user-id

(current-effective-user-id) procedure

[setter] (set! (current-effective-user-id) UID)

Get or set the effective user-id of the current process.

user-information

(user-information USER [AS-VECTOR]) procedure: If USER specifes a valid username (as a string) or user ID, then the user database is consulted and a list of 7 values are returned: the user-name, the encrypted password, the user ID, the group ID, a user-specific string, the home directory and the default shell. When AS-VECTOR is #t a vector of 7 elements is returned instead of a list. If no user with this name or id then #f is returned.

current-group-id

(current-group-id) procedure

[setter] (set! (current-group-id) GID)

Get or set the real group-id of the current process.

current-effective-group-id

(current-effective-group-id) procedure

[setter] (set! (current-effective-group-id) GID)

Get or set the effective group-id of the current process. ID can be found, then #f is returned.

group-information

(group-information GROUP) procedure: If GROUP specifies a valid group-name or group-id, then this procedure returns a list of four values: the group-name, the encrypted group password, the group ID and a list of the names of all group members. If no group with the given name or ID exists, then #f is returned.

get-groups

(get-groups) procedure: Returns a list with the supplementary group IDs of the current user.

Changing user & group information

set-groups!

(set-groups! GIDLIST) procedure

Sets the supplementrary group IDs of the current user to the IDs given in the list GIDLIST.

Only the superuser may invoke this procedure.

initialize-groups

(initialize-groups USERNAME BASEGID) procedure

Sets the supplementrary group IDs of the current user to the IDs from the user with name USERNAME (a string), including BASEGID.

Only the superuser may invoke this procedure.

set-process-group-id!

(set-process-group-id! PID PGID) procedure

[setter] (set! (process-group-id PID) PGID)

Sets the process group ID of the process specifed by PID to PGID.

Record locking

file-lock

(file-lock PORT [START [LEN]]) procedure: Locks the file associated with PORT for reading or writing (according to whether PORT is an input- or output-port). START specifies the starting position in the file to be locked and defaults to 0. LEN specifies the length of the portion to be locked and defaults to #t, which means the complete file. file-lock returns a lock-object.

file-lock/blocking

(file-lock/blocking PORT [START [LEN]]) procedure: Similar to file-lock, but if a lock is held on the file, the current process blocks (including all threads) until the lock is released.

file-test-lock

(file-test-lock PORT [START [LEN]]) procedure: Tests whether the file associated with PORT is locked for reading or writing (according to whether PORT is an input- or output-port) and returns either #f or the process-id of the locking process.

file-unlock

(file-unlock LOCK) procedure: Unlocks the previously locked portion of a file given in LOCK.

Signal handling

set-alarm!

(set-alarm! SECONDS) procedure: Sets an internal timer to raise the signal/alrm after SECONDS are elapsed. You can use the set-signal-handler! procedure to write a handler for this signal.

set-signal-handler!